<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>Hoodoo::ActiveRecord::Finder::ClassMethods</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" href="../../../../css/reset.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../../css/main.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../../css/github.css" type="text/css" media="screen" />
<script src="../../../../js/jquery-1.3.2.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../../js/jquery-effect.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../../js/main.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../../js/highlight.pack.js" type="text/javascript" charset="utf-8"></script>

</head>

<body>
    <div class="banner">
        <h1>
            <span class="type">Module</span>
            Hoodoo::ActiveRecord::Finder::ClassMethods
        </h1>
        <ul class="files">
            <li><a href="../../../../files/lib/hoodoo/active/active_record/finder_rb.html">lib/hoodoo/active/active_record/finder.rb</a></li>
        </ul>
    </div>
    <div id="bodyContent">
        <div id="content">
    <div class="description">
      
<p>Collection of class methods that get defined on an including class via <a
href="../Finder.html#method-c-included">Hoodoo::ActiveRecord::Finder.included</a>.</p>

    </div>








    <!-- Method ref -->
    <div class="sectiontitle">Methods</div>
    <dl class="methods">
        <dt>A</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-acquire">acquire</a>,
              </li>
              <li>
                <a href="#method-i-acquire_in">acquire_in</a>,
              </li>
              <li>
                <a href="#method-i-acquire_with">acquire_with</a>,
              </li>
              <li>
                <a href="#method-i-acquire_with_id_substitute">acquire_with_id_substitute</a>,
              </li>
              <li>
                <a href="#method-i-acquired_with">acquired_with</a>,
              </li>
              <li>
                <a href="#method-i-acquisition_scope">acquisition_scope</a>
              </li>
          </ul>
        </dd>
        <dt>D</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-dataset_size">dataset_size</a>
              </li>
          </ul>
        </dd>
        <dt>E</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-estimate_counts_with">estimate_counts_with</a>,
              </li>
              <li>
                <a href="#method-i-estimated_count">estimated_count</a>,
              </li>
              <li>
                <a href="#method-i-estimated_dataset_size">estimated_dataset_size</a>
              </li>
          </ul>
        </dd>
        <dt>F</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-filter_with">filter_with</a>
              </li>
          </ul>
        </dd>
        <dt>L</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-list">list</a>,
              </li>
              <li>
                <a href="#method-i-list_filter_map">list_filter_map</a>,
              </li>
              <li>
                <a href="#method-i-list_finder">list_finder</a>,
              </li>
              <li>
                <a href="#method-i-list_in">list_in</a>,
              </li>
              <li>
                <a href="#method-i-list_search_map">list_search_map</a>
              </li>
          </ul>
        </dd>
        <dt>P</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-polymorphic_find">polymorphic_find</a>,
              </li>
              <li>
                <a href="#method-i-polymorphic_id_fields">polymorphic_id_fields</a>
              </li>
          </ul>
        </dd>
        <dt>S</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-scoped_in">scoped_in</a>,
              </li>
              <li>
                <a href="#method-i-search_with">search_with</a>
              </li>
          </ul>
        </dd>
    </dl>










    <!-- Methods -->
      <div class="sectiontitle">Instance Public methods</div>
        <div class="method">
          <div class="title method-title" id="method-i-acquire">
              <b>acquire</b>( ident )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-acquire" name="method-i-acquire" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>“Polymorphic” find - support for finding a model by fields other than just
<code>:id</code>, based on a single unique identifier. Use <a
href="ClassMethods.html#method-i-acquire">acquire</a> just like you&#39;d
use <code>find_by_id</code> and only bother with it if you support finding
a resource instance by <code>id</code> <em>and</em> one or more other model
fields. Otherwise, just use <code>find_by_id</code>.</p>

<p>In the model, you declare the list of fields <em>in</em> <em>addition</em>
<em>to</em> <code>id</code> by calling <a
href="ClassMethods.html#method-i-acquire_with">acquire_with</a> thus:</p>

<pre><code>class SomeModel &lt; ActiveRecord::Base
  include Hoodoo::ActiveRecord::Finder
  acquire_with ... # &lt;list-of-other-fields&gt;
end</code></pre>

<p>For example, maybe you allow some resource to be looked up by fields
<code>id</code> or <code>code</code>, both of which are independently
unique sets. Since <code>id</code> is always automatically included, you
only need to do this:</p>

<pre><code>class SomeModel &lt; ActiveRecord::Base
  include Hoodoo::ActiveRecord::Finder
  acquire_with :code
end
</code></pre>

<p>Then, in a resource&#39;s implementation:</p>

<pre><code>def show( context )
  found = SomeModel.acquire( context.request.ident )
  return context.response.not_found( context.request.ident ) if found.nil?

  # ...map &#39;found&#39; to whatever resource you&#39;re representing,
  # e.g. via a Hoodoo::Presenters::Base subclass with resource
  # schema and the subclass&#39;s Hoodoo::Presenters::Base::render
  # call, then...

  context.response.set_resource( resource_representation_of_found )
end
</code></pre>

<p>There is nothing magic “under the hood” - <a
href="../../../Hoodoo.html">Hoodoo</a> just tries to find records with a
value matching the incoming identifier for each of the fields in turn. It
starts with <code>id</code> then runs through any other fields in the order
given through <a
href="ClassMethods.html#method-i-acquire_with">acquire_with</a>.</p>

<p>This can only be used <em>if your searched fields are strings</em> in the
database. This includes, for example, the <code>id</code> column; <a
href="../../../Hoodoo.html">Hoodoo</a> usually expects to be a string field
holding a 32-character <a href="../UUID.html">UUID</a>. If any of the
fields contain non-string types, attempts to use the <a
href="ClassMethods.html#method-i-acquire">acquire</a> mechanism (or a
related one) may result in database errors due to type mismatches,
depending upon the database engine in use.</p>

<p>In more complex scenarious, you can just call <a
href="ClassMethods.html#method-i-acquire">acquire</a> at the end of any
chain of AREL queries just as you would call ActiveRecord&#39;s own
find_by_id method, e.g.:</p>

<pre><code>SomeModel.where( :foo =&gt; :bar ).acquire( context.request.ident )
</code></pre>

<p>Usually for convenience you should use <a
href="ClassMethods.html#method-i-acquire_in">acquire_in</a> instead, or
only call <a href="ClassMethods.html#method-i-acquire">acquire</a> with
(say) a secure scope via for example a call to <a
href="../Secure/ClassMethods.html#method-i-secure">Hoodoo::ActiveRecord::Secure::ClassMethods#secure</a>.
Other scopes may be needed depending on the mixins your model uses.</p>
<dl class="rdoc-list note-list"><dt><code>ident</code>
<dd>
<p>The value to search for in the fields (attributes) specified via <a
href="ClassMethods.html#method-i-acquire_with">acquire_with</a>, matched
using calls to <code>where( attr =&gt; ident )</code>.</p>
</dd></dl>

<p>Returns a found model instance or <code>nil</code> for no match.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-acquire_source')" id="l_method-i-acquire_source">show</a>
              </p>
              <div id="method-i-acquire_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 179</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">acquire</span>( <span class="ruby-identifier">ident</span> )
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">acquisition_scope</span>( <span class="ruby-identifier">ident</span> ).<span class="ruby-identifier">first</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-acquire_in">
              <b>acquire_in</b>( context )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-acquire_in" name="method-i-acquire_in" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Implicily secure, translated, dated etc. etc. version of <a
href="ClassMethods.html#method-i-acquire">acquire</a>, according to which
modules are mixed into your model class. Uses <a
href="ClassMethods.html#method-i-scoped_in">scoped_in</a> to obtain a base
scope in which to operate, so it is “mixin aware” and incorporates other <a
href="../../../Hoodoo.html">Hoodoo</a> extensions within the wider scope
chain. See that method&#39;s documentation for more information.</p>

<p>For example, if you are using or at some point intend to mix in and use the
mechanism described by the likes of <a
href="../Secure/ClassMethods.html#method-i-secure">Hoodoo::ActiveRecord::Secure::ClassMethods#secure</a>,
call here as a convenience to both obtain a secure context and find a
record (with or without additional find-by fields other than
<code>id</code>) in one go. Building on the example from <a
href="../Secure/ClassMethods.html#method-i-secure">Hoodoo::ActiveRecord::Secure::ClassMethods#secure</a>,
we might have an Audit model as follows:</p>

<pre><code>class Audit &lt; ActiveRecord::Base
  include Hoodoo::ActiveRecord::Secure

  secure_with( {
    :creating_caller_uuid =&gt; :authorised_caller_uuid
  } )

  # Plus perhaps a call to &quot;acquire_with&quot;
end
</code></pre>

<p>Then, in a resource&#39;s implementation:</p>

<pre><code>def show( context )
  found = SomeModel.acquire_in( context )
  return context.response.not_found( context.request.ident ) if found.nil?

  # ...map &#39;found&#39; to whatever resource you&#39;re representing,
  # e.g. via a Hoodoo::Presenters::Base subclass with resource
  # schema and the subclass&#39;s Hoodoo::Presenters::Base::render
  # call, then...

  context.response.set_resource( resource_representation_of_found )
end
</code></pre>

<p>The value of <code>found</code> will be acquired within the secure context
determined by the prevailing call context (and its session), so the data it
finds is inherently correctly scoped - provided your model&#39;s <a
href="../Secure/ClassMethods.html#method-i-secure_with">Hoodoo::ActiveRecord::Secure::ClassMethods#secure_with</a>
call describes things correctly.</p>

<p>This method is for convenience and safety - you can&#39;t accidentally
forget the secure scope:</p>

<pre><code>SomeModel.secure( context ).acquire( context.request.ident )

# ...has the same result as...

SomeModel.acquire_in( context )
</code></pre>

<p>The same applies to forgetting dated scopes, translated scopes, or anything
else that <a href="ClassMethods.html#method-i-scoped_in">scoped_in</a>
might include for you.</p>

<p>Parameters:</p>
<dl class="rdoc-list note-list"><dt><code>context</code>
<dd>
<p><a href="../../Services/Context.html">Hoodoo::Services::Context</a>
instance describing a call context. This is typically a value passed to one
of the <a
href="../../Services/Implementation.html">Hoodoo::Services::Implementation</a>
instance methods that a resource subclass implements.</p>
</dd></dl>

<p>Returns a found model instance or <code>nil</code> for no match.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-acquire_in_source')" id="l_method-i-acquire_in_source">show</a>
              </p>
              <div id="method-i-acquire_in_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 250</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">acquire_in</span>( <span class="ruby-identifier">context</span> )
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">scoped_in</span>( <span class="ruby-identifier">context</span> ).<span class="ruby-identifier">acquire</span>( <span class="ruby-identifier">context</span>.<span class="ruby-identifier">request</span>.<span class="ruby-identifier">ident</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-acquire_with">
              <b>acquire_with</b>( *args )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-acquire_with" name="method-i-acquire_with" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Describe the list of model fields <em>in</em> <em>addition</em> <em>to</em>
<code>id</code> which are to be used to “find-by-identifier” through calls
<a href="ClassMethods.html#method-i-acquire">acquire</a> and <a
href="ClassMethods.html#method-i-acquire_in">acquire_in</a>. See those
methods for more details.</p>

<p>Fields will be searched in the order listed. If duplicate items are
present, the first occurrence is kept and the rest are removed.</p>
<dl class="rdoc-list note-list"><dt>*args
<dd>
<p>One or more field names as Strings or Symbols.</p>
</dd></dl>

<p>See also: <a
href="ClassMethods.html#method-i-acquired_with">acquired_with</a></p>

<pre><code>#acquire_with_id_substitute
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-acquire_with_source')" id="l_method-i-acquire_with_source">show</a>
              </p>
              <div id="method-i-acquire_with_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 266</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">acquire_with</span>( <span class="ruby-operator">*</span><span class="ruby-identifier">args</span> )
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">nz_co_loyalty_hoodoo_show_id_fields</span> = <span class="ruby-identifier">args</span>.<span class="ruby-identifier">map</span>( <span class="ruby-operator">&amp;</span> <span class="ruby-value">:to_s</span> )
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">nz_co_loyalty_hoodoo_show_id_fields</span>.<span class="ruby-identifier">uniq!</span>()
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-acquire_with_id_substitute">
              <b>acquire_with_id_substitute</b>( attr )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-acquire_with_id_substitute" name="method-i-acquire_with_id_substitute" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>The <a href="ClassMethods.html#method-i-acquire_with">acquire_with</a>
method allows methods like <a
href="ClassMethods.html#method-i-acquire">acquire</a> and <a
href="ClassMethods.html#method-i-acquire_in">acquire_in</a> to
transparently find a record based on <em>one</em> <em>or</em> <em>more</em>
columns in the database. The columns (and corresponding model attributes)
specified through a call to <a
href="ClassMethods.html#method-i-acquire_with">acquire_with</a> will
normally be used <em>in</em> <em>addition</em> <em>to</em> a lookup on the
<code>id</code> column, but in rare circumstances you might need to bypass
that and use an entirely different field. This is distinct from the
ActiveRecord-level concept of the model&#39;s primary key column.</p>

<p>To permanently change the use of the <code>id</code> attribute as the first
search parameter in <a
href="ClassMethods.html#method-i-acquire">acquire</a> and <a
href="ClassMethods.html#method-i-acquire_in">acquire_in</a>, by modifying
the behaviour of <a
href="ClassMethods.html#method-i-acquisition_scope">acquisition_scope</a>,
call here and pass in the new attribute name.</p>
<dl class="rdoc-list note-list"><dt><code>attr</code>
<dd>
<p>Attribute name as a Symbol or String to use <em>instead</em> of
<code>id</code>, as a default mandatory column in <a
href="ClassMethods.html#method-i-acquisition_scope">acquisition_scope</a>.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-acquire_with_id_substitute_source')" id="l_method-i-acquire_with_id_substitute_source">show</a>
              </p>
              <div id="method-i-acquire_with_id_substitute_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 301</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">acquire_with_id_substitute</span>( <span class="ruby-identifier">attr</span> )
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">nz_co_loyalty_hoodoo_show_id_substitute</span> = <span class="ruby-identifier">attr</span>.<span class="ruby-identifier">to_sym</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-acquired_with">
              <b>acquired_with</b>()
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-acquired_with" name="method-i-acquired_with" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Return the list of model fields <em>in</em> <em>addition</em> <em>to</em>
<code>id</code> which are being used to “find-by-identifier” through calls
to <a href="ClassMethods.html#method-i-acquire">acquire</a> and <a
href="ClassMethods.html#method-i-acquire_in">acquire_in</a>. The returned
Array contains de-duplicated String values only.</p>

<p>See also: <a
href="ClassMethods.html#method-i-acquire_with">acquire_with</a></p>

<pre><code>#acquire_with_id_substitute
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-acquired_with_source')" id="l_method-i-acquired_with_source">show</a>
              </p>
              <div id="method-i-acquired_with_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 279</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">acquired_with</span>
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">nz_co_loyalty_hoodoo_show_id_fields</span> <span class="ruby-operator">||</span> []
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-acquisition_scope">
              <b>acquisition_scope</b>( ident )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-acquisition_scope" name="method-i-acquisition_scope" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Back-end to <a href="ClassMethods.html#method-i-acquire">acquire</a> and
therefore, in turn, <a
href="ClassMethods.html#method-i-acquire_in">acquire_in</a>. Returns an
ActiveRecord::Relation instance which scopes the search for a record by
<code>id</code> and across any other columns specified by <a
href="ClassMethods.html#method-i-acquire_with">acquire_with</a>, via SQL
<code>OR</code>.</p>

<p>If you need to change the use of attribute <code>id</code>, specify a
different attribute with <a
href="ClassMethods.html#method-i-acquire_with_id_substitute">acquire_with_id_substitute</a>.
In that case, the given attribute is searched for instead of
<code>id</code>; either way, a default starting attribute <em>will</em> be
used in scope in addition to any extra fields specified using <a
href="ClassMethods.html#method-i-acquire_with">acquire_with</a>.</p>

<p>Normally such a scope could only ever return a single record based on an
assuption of uniqueness constraints around columns which one might use in
an equivalent of a <code>find</code> call. This scope is often chained on
top of a wider listing scope provided by <a
href="ClassMethods.html#method-i-scoped_in">scoped_in</a> to create a fully
context-aware, secure, dated, translated etc. query. It is possible however
that the chosen <code>ident</code> value might not resolve to a single
unique record depending on how your data works and you may need to manually
apply additional constraints to the returned ActiveRecord::Relation
instance.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-acquisition_scope_source')" id="l_method-i-acquisition_scope_source">show</a>
              </p>
              <div id="method-i-acquisition_scope_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 326</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">acquisition_scope</span>( <span class="ruby-identifier">ident</span> )
  <span class="ruby-identifier">extra_fields</span> = <span class="ruby-keyword">self</span>.<span class="ruby-identifier">acquired_with</span>()
  <span class="ruby-identifier">arel_table</span>   = <span class="ruby-keyword">self</span>.<span class="ruby-identifier">arel_table</span>()
  <span class="ruby-identifier">arel_query</span>   = <span class="ruby-identifier">arel_table</span>[ <span class="ruby-keyword">self</span>.<span class="ruby-identifier">nz_co_loyalty_hoodoo_show_id_substitute</span> <span class="ruby-operator">||</span> <span class="ruby-value">:id</span> ].<span class="ruby-identifier">eq</span>( <span class="ruby-identifier">ident</span> )

  <span class="ruby-identifier">extra_fields</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">field</span> <span class="ruby-operator">|</span>
    <span class="ruby-identifier">arel_query</span> = <span class="ruby-identifier">arel_query</span>.<span class="ruby-identifier">or</span>( <span class="ruby-identifier">arel_table</span>[ <span class="ruby-identifier">field</span> ].<span class="ruby-identifier">eq</span>( <span class="ruby-identifier">ident</span> ) )
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">return</span> <span class="ruby-identifier">where</span>( <span class="ruby-identifier">arel_query</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-dataset_size">
              <b>dataset_size</b>()
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-dataset_size" name="method-i-dataset_size" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Given some scope - typically that obtained from a prior call to <a
href="ClassMethods.html#method-i-list">list</a> or <a
href="ClassMethods.html#method-i-list_in">list_in</a>, with possibly other
query modifiers too - return the total dataset size. This is basically a
<code>COUNT</code> operation, but run without offset or limit
considerations (ignoring pagination).</p>

<p>This is particularly useful if you are calling <a
href="../../Services/Response.html#method-i-set_resources">Hoodoo::Services::Response#set_resources</a>
and want to fill in its <code>dataset_size</code> parameter.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-dataset_size_source')" id="l_method-i-dataset_size_source">show</a>
              </p>
              <div id="method-i-dataset_size_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 503</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">dataset_size</span>
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">all</span>.<span class="ruby-identifier">limit</span>( <span class="ruby-keyword">nil</span> ).<span class="ruby-identifier">offset</span>( <span class="ruby-keyword">nil</span> ).<span class="ruby-identifier">count</span>()
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-estimate_counts_with">
              <b>estimate_counts_with</b>( proc )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-estimate_counts_with" name="method-i-estimate_counts_with" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>This method is related to <a
href="ClassMethods.html#method-i-estimated_count">estimated_count</a>, so
read the documentation for that as an introduction first.</p>

<p>In <a
href="ClassMethods.html#method-i-estimated_count">estimated_count</a>, a
PostgreSQL example is given. Continuing with this, we could implement an
estimation mechanism via Hoodoo&#39;s fast counter with something like the
approach described here:</p>
<ul><li>
<p><a
href="https://wiki.postgresql.org/wiki/Count_estimate">wiki.postgresql.org/wiki/Count_estimate</a></p>
</li><li>
<p><a
href="http://www.verygoodindicators.com/blog/2015/04/07/faster-count-queries">www.verygoodindicators.com/blog/2015/04/07/faster-count-queries</a>/</p>
</li></ul>

<p>First, you would need a migration in your service to implement the
estimation method as a PLPGSQL function:</p>

<pre><code>class CreateFastCountFunction &lt; ActiveRecord::Migration
  def up
    execute &lt;&lt;-SQL
      CREATE FUNCTION estimated_count(query text) RETURNS integer AS
      $func$
      DECLARE
          rec   record;
          rows  integer;
      BEGIN
          FOR rec IN EXECUTE &#39;EXPLAIN &#39; || query LOOP
              rows := substring(rec.&quot;QUERY PLAN&quot; FROM &#39; rows=([[:digit:]]+)&#39;);
              EXIT WHEN rows IS NOT NULL;
          END LOOP;

          RETURN rows;
      END
      $func$ LANGUAGE plpgsql;
    SQL
  end

  def down
    execute &quot;DROP FUNCTION estimated_count(query text);&quot;
  end
end
</code></pre>

<p>This takes arbitrary query text so should cope with pretty much any kind of
<a href="../../ActiveRecord.html">ActiveRecord</a> query chain and
resulting SQL. Run the database migration, then define a Proc which calls
the new function:</p>

<pre><code>counter = Proc.new do | sql |
  begin
    sql = sql.gsub( &quot;&#39;&quot;, &quot;&#39;&#39;&quot; ) # Escape SQL for insertion below
    ActiveRecord::Base.connection.execute(
      &quot;SELECT estimated_count(&#39;#{ sql }&#39;)&quot;
    ).first[ &#39;estimated_count&#39; ].to_i
  rescue
    nil
end</code></pre>

<p>Suppose we have a model called <code>Purchase</code>; next tell this model
to use the above Proc for fast counting and use it:</p>

<pre><code>Purchase.estimate_counts_with( counter )

Purchase.estimated_count()
# =&gt; An integer; and you can use scope chains, just like #count:
Purchase.where(...conditions...).estimated_count()
# =&gt; An integer</code></pre>

<p>A real-life example showing how running PostgreSQL&#39;s
<code>ANALYZE</code> command can make a difference:</p>

<pre><code>[1] pry(main)&gt; Purchase.estimated_count
=&gt; 68
[2] pry(main)&gt; Purchase.count
=&gt; 76
[3] pry(main)&gt; ActiveRecord::Base.connection.execute( &#39;ANALYZE&#39; )
=&gt; #&lt;PG::Result:0x007f89b62cdcc8 status=PGRES_COMMAND_OK ntuples=0 nfields=0 cmd_tuples=0&gt;
[4] pry(main)&gt; Purchase.estimated_count
=&gt; 76</code></pre>

<p>Parameters:</p>
<dl class="rdoc-list note-list"><dt><code>proc</code>
<dd>
<p>The Proc to call. It must accept one parameter, which is the SQL query for
which the count is to be run, as a String. It must evaluate to an Integer
estimation, or <code>nil</code> if it is not able to provide any/useful
estimations, in its opinion.</p>

<p>Pass <code>nil</code> to remove the custom counter method and restore
default behaviour.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-estimate_counts_with_source')" id="l_method-i-estimate_counts_with_source">show</a>
              </p>
              <div id="method-i-estimate_counts_with_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 633</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">estimate_counts_with</span>( <span class="ruby-identifier">proc</span> )
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">nz_co_loyalty_hoodoo_estimate_counts_with</span> = <span class="ruby-identifier">proc</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-estimated_count">
              <b>estimated_count</b>()
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-estimated_count" name="method-i-estimated_count" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>In absence of other configuration, this method just calls through to Active
Record&#39;s count, but you can override the counting mechanism with a Proc
which gets called to do the counting instead.</p>

<p>The use case is for databases where counting may be slow for some reason.
For example, in PostgreSQL 9, the MVCC model means that big tables under
heavy write load may take extremely long times to be counted as a full
sequential row scan gets activated. In the case of PostgreSQL, there&#39;s
an estimation available as an alternative; its accuracy depends on how
often the <code>ANALYZE</code> command is run, but at least its execution
speed is always very small.</p>

<p>The <a
href="ClassMethods.html#method-i-estimated_dataset_size">estimated_dataset_size</a>
method runs through here for counting so you need to ensure that your count
estimation method can cope with whatever queries that might arise from the
scope chains involved in instances of the model at hand, within the service
code that uses that model.</p>

<p>Specify a count estimation Proc with <a
href="ClassMethods.html#method-i-estimate_counts_with">estimate_counts_with</a>.
Such blocks are permitted to return <code>nil</code> if the estimation is
considered to be wildly wrong or unobtainable; in that case, the returned
value for the estimated count will be <code>nil</code> too.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-estimated_count_source')" id="l_method-i-estimated_count_source">show</a>
              </p>
              <div id="method-i-estimated_count_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 539</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">estimated_count</span>
  <span class="ruby-identifier">counter</span> = <span class="ruby-keyword">self</span>.<span class="ruby-identifier">nz_co_loyalty_hoodoo_estimate_counts_with</span>

  <span class="ruby-keyword">if</span> ( <span class="ruby-identifier">counter</span>.<span class="ruby-identifier">nil?</span> )
    <span class="ruby-keyword">return</span> <span class="ruby-identifier">all</span>.<span class="ruby-identifier">count</span>
  <span class="ruby-keyword">else</span>
    <span class="ruby-keyword">return</span> <span class="ruby-identifier">counter</span>.<span class="ruby-identifier">call</span>( <span class="ruby-identifier">all</span>.<span class="ruby-identifier">to_sql</span> )
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-estimated_dataset_size">
              <b>estimated_dataset_size</b>()
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-estimated_dataset_size" name="method-i-estimated_dataset_size" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>As <a href="ClassMethods.html#method-i-dataset_size">dataset_size</a>, but
allows a configurable counting back-end via <a
href="ClassMethods.html#method-i-estimated_count">estimated_count</a> and
<a
href="ClassMethods.html#method-i-estimate_counts_with">estimate_counts_with</a>.
This method is intended to be used for fast count estimations, usually for
performance reasons if an accurate <a
href="ClassMethods.html#method-i-dataset_size">dataset_size</a> count is
too slow to compute.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-estimated_dataset_size_source')" id="l_method-i-estimated_dataset_size_source">show</a>
              </p>
              <div id="method-i-estimated_dataset_size_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 512</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">estimated_dataset_size</span>
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">all</span>.<span class="ruby-identifier">limit</span>( <span class="ruby-keyword">nil</span> ).<span class="ruby-identifier">offset</span>( <span class="ruby-keyword">nil</span> ).<span class="ruby-identifier">estimated_count</span>()
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-filter_with">
              <b>filter_with</b>( hash )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-filter_with" name="method-i-filter_with" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>As <a href="ClassMethods.html#method-i-search_with">search_with</a>, but
used in <code>where.not</code> queries.</p>

<p><strong><em>IMPORTANT:</em></strong> Beware <code>null</code> column values
and filters given SQL&#39;s strange behaviour with such things. The search
helpers in <a
href="SearchHelper.html">Hoodoo::ActiveRecord::Finder::SearchHelper</a>
class will work as logically expected (“field not &#39;foo&#39;” will find
fields with a null value), though if you&#39;re expecting SQL-like
behaviour it might come as a surprise! Using <code>...AND field IS NOT
NULL</code> in queries for <code>filter_with</code> tends to work
reasonably when the query is negated for filter use via
<code>...NOT(...)...</code>. Examining the implementation of <a
href="SearchHelper.html">Hoodoo::ActiveRecord::Finder::SearchHelper</a> may
help if confused. See also:</p>
<ul><li>
<p><a
href="https://en.wikipedia.org/wiki/Null_(SQL">en.wikipedia.org/wiki/Null_(SQL</a>)</p>
</li></ul>
<dl class="rdoc-list note-list"><dt><code>map</code>
<dd>
<p>As <a href="ClassMethods.html#method-i-search_with">search_with</a>.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-filter_with_source')" id="l_method-i-filter_with_source">show</a>
              </p>
              <div id="method-i-filter_with_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 737</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">filter_with</span>( <span class="ruby-identifier">hash</span> )
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">nz_co_loyalty_hoodoo_filter_with</span> = <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">ActiveRecord</span><span class="ruby-operator">::</span><span class="ruby-constant">Support</span>.<span class="ruby-identifier">process_to_map</span>( <span class="ruby-identifier">hash</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-list">
              <b>list</b>( list_parameters )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-list" name="method-i-list" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Generate an ActiveRecord::Relation instance which can be used to count,
retrieve or further refine a list of model instances from the database.</p>

<p>Usually for convenience you should use <a
href="ClassMethods.html#method-i-list_in">list_in</a> instead, or only call
<a href="ClassMethods.html#method-i-acquire">acquire</a> with (say) a
secure scope via for example a call to <a
href="../Secure/ClassMethods.html#method-i-secure">Hoodoo::ActiveRecord::Secure::ClassMethods#secure</a>.
An example of this second option is shown below.</p>

<p>Pass a <a
href="../../Services/Request/ListParameters.html">Hoodoo::Services::Request::ListParameters</a>
instance, e.g. via the <a
href="../../Services/Context.html">Hoodoo::Services::Context</a> instance
passed to resource endpoint implementations and accessor
<code>context.request.list</code>. It takes into account the list offset,
limit, sort key and sort direction automatically. In addition, it can do
simple search and filter operations if search and filter mappings are set
up via <a href="ClassMethods.html#method-i-search_with">search_with</a> and
<a href="ClassMethods.html#method-i-filter_with">filter_with</a>.</p>

<p>For exampe, in a simple case where a model can be listed without any
unusual constraints, we might do this:</p>

<pre><code>class SomeModel &lt; ActiveRecord::Base
  include Hoodoo::ActiveRecord::Finder

  search_with # ...&lt;field-to-search-info mapping&gt;
  # ...and/or...
  filter_with # ...&lt;field-to-search-info mapping&gt;
end

# ...then, in the resource implementation...

def list( context )
  finder = SomeModel.list( context.request.list )
  results = finder.all.map do | item |
    # ...map database objects to response objects...
  end
  context.response.set_resources( results, finder.dataset_size )
end
</code></pre>

<p>Note the use of helper method <a
href="ClassMethods.html#method-i-dataset_size">dataset_size</a> to count
the total amount of results in the dataset without pagination. A resource
may alternatively choose to use <a
href="ClassMethods.html#method-i-estimated_dataset_size">estimated_dataset_size</a>
for a fast count estimation, or neither (though this is generally not
recommended) or</p>
<ul><li>
<p>permissible but unusual - include both.</p>

<pre><code>context.response.set_resources( results, nil, finder.estimated_dataset_size )
</code></pre>
</li></ul>

<p>The service middleware enforces sane values for things like list offsets,
sort keys and so-on according to service interface definitions, so if using
the middleware you don&#39;t need to do any extra checking yourself.</p>

<p>Since the returned object is just a relation, adding further constraints is
easy - call things like <code>where</code>, <code>group</code> and so-on as
normal. You can also list in a secure context via the included <a
href="../Secure/ClassMethods.html#method-i-secure">Hoodoo::ActiveRecord::Secure::ClassMethods#secure</a>,
assuming appropriate data is set in the model via <a
href="../Secure/ClassMethods.html#method-i-secure_with">Hoodoo::ActiveRecord::Secure::ClassMethods#secure_with</a>:</p>

<pre><code>def list( context )
  finder = SomeModel.secure( context ).list( context.request.list )
  finder = finder.where( :additional_filter =&gt; &#39;some value&#39; )
  results = finder.all.map do | item |
    # ...map database objects to response objects...
  end
  context.response.set_resources( results, finder.dataset_size )
end
</code></pre>

<p>Since it&#39;s just a chained scope, you can call in any order:</p>

<pre><code>SomeModel.secure( context ).list( context.request.list )

# ...has the same result as...

SomeModel.list( context.request.list ).secure( context )
</code></pre>

<p>Any of the ActiveRecord::QueryMethods can be called on the returned value.
See:</p>

<p><a
href="http://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html">api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html</a></p>
<dl class="rdoc-list note-list"><dt><code>list_parameters</code>
<dd>
<p><a
href="../../Services/Request/ListParameters.html">Hoodoo::Services::Request::ListParameters</a>
instance, typically obtained from the <a
href="../../Services/Context.html">Hoodoo::Services::Context</a> instance
passed to a service implementation in <a
href="../../Services/Implementation.html#method-i-list">Hoodoo::Services::Implementation#list</a>,
via <code>context.request.list</code> (i.e. <a
href="../../Services/Context.html#attribute-i-request">Hoodoo::Services::Context#request</a>
/ <a
href="../../Services/Request.html#attribute-i-list">Hoodoo::Services::Request#list</a>).</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-list_source')" id="l_method-i-list_source">show</a>
              </p>
              <div id="method-i-list_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 427</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">list</span>( <span class="ruby-identifier">list_parameters</span> )
  <span class="ruby-identifier">finder</span> = <span class="ruby-identifier">all</span>.<span class="ruby-identifier">offset</span>( <span class="ruby-identifier">list_parameters</span>.<span class="ruby-identifier">offset</span> ).<span class="ruby-identifier">limit</span>( <span class="ruby-identifier">list_parameters</span>.<span class="ruby-identifier">limit</span> )
  <span class="ruby-identifier">finder</span> = <span class="ruby-identifier">finder</span>.<span class="ruby-identifier">order</span>( <span class="ruby-identifier">list_parameters</span>.<span class="ruby-identifier">sort_data</span> )

  <span class="ruby-comment"># DRY up the &#39;each&#39; loops below. Use a Proc not a method because any</span>
  <span class="ruby-comment"># methods we define will end up being defined on the including Model,</span>
  <span class="ruby-comment"># increasing the chance of a name collision.</span>
  <span class="ruby-comment">#</span>
  <span class="ruby-identifier">dry_proc</span> = <span class="ruby-constant">Proc</span>.<span class="ruby-identifier">new</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">data</span>, <span class="ruby-identifier">attr</span>, <span class="ruby-identifier">proc</span> <span class="ruby-operator">|</span>
    <span class="ruby-identifier">value</span> = <span class="ruby-identifier">data</span>[ <span class="ruby-identifier">attr</span> ]
    <span class="ruby-identifier">proc</span>.<span class="ruby-identifier">call</span>( <span class="ruby-identifier">attr</span>, <span class="ruby-identifier">value</span> ) <span class="ruby-keyword">unless</span> <span class="ruby-identifier">value</span>.<span class="ruby-identifier">nil?</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-identifier">search_map</span> = <span class="ruby-keyword">self</span>.<span class="ruby-identifier">nz_co_loyalty_hoodoo_search_with</span>

  <span class="ruby-keyword">unless</span> <span class="ruby-identifier">search_map</span>.<span class="ruby-identifier">nil?</span>
    <span class="ruby-identifier">search_map</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">attr</span>, <span class="ruby-identifier">proc</span> <span class="ruby-operator">|</span>
      <span class="ruby-identifier">args</span>   = <span class="ruby-identifier">dry_proc</span>.<span class="ruby-identifier">call</span>( <span class="ruby-identifier">list_parameters</span>.<span class="ruby-identifier">search_data</span>, <span class="ruby-identifier">attr</span>, <span class="ruby-identifier">proc</span> )
      <span class="ruby-identifier">finder</span> = <span class="ruby-identifier">finder</span>.<span class="ruby-identifier">where</span>( <span class="ruby-operator">*</span><span class="ruby-identifier">args</span> ) <span class="ruby-keyword">unless</span> <span class="ruby-identifier">args</span>.<span class="ruby-identifier">nil?</span>
    <span class="ruby-keyword">end</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-identifier">filter_map</span> = <span class="ruby-keyword">self</span>.<span class="ruby-identifier">nz_co_loyalty_hoodoo_filter_with</span>

  <span class="ruby-keyword">unless</span> <span class="ruby-identifier">filter_map</span>.<span class="ruby-identifier">nil?</span>
    <span class="ruby-identifier">filter_map</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">attr</span>, <span class="ruby-identifier">proc</span> <span class="ruby-operator">|</span>
      <span class="ruby-identifier">args</span>   = <span class="ruby-identifier">dry_proc</span>.<span class="ruby-identifier">call</span>( <span class="ruby-identifier">list_parameters</span>.<span class="ruby-identifier">filter_data</span>, <span class="ruby-identifier">attr</span>, <span class="ruby-identifier">proc</span> )
      <span class="ruby-identifier">finder</span> = <span class="ruby-identifier">finder</span>.<span class="ruby-identifier">where</span>.<span class="ruby-identifier">not</span>( <span class="ruby-operator">*</span><span class="ruby-identifier">args</span> ) <span class="ruby-keyword">unless</span> <span class="ruby-identifier">args</span>.<span class="ruby-identifier">nil?</span>
    <span class="ruby-keyword">end</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">return</span> <span class="ruby-identifier">finder</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-list_filter_map">
              <b>list_filter_map</b>( map )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-list_filter_map" name="method-i-list_filter_map" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Deprecated interface replaced by <a
href="ClassMethods.html#method-i-filter_with">filter_with</a> (this is an
alias).</p>
<dl class="rdoc-list note-list"><dt>map
<dd>
<p>Passed to <a href="ClassMethods.html#method-i-filter_with">filter_with</a>.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-list_filter_map_source')" id="l_method-i-list_filter_map_source">show</a>
              </p>
              <div id="method-i-list_filter_map_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 794</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">list_filter_map</span>( <span class="ruby-identifier">map</span> )
  <span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span>( <span class="ruby-string">&#39;Hoodoo:ActiveRecord::Finder#list_filter_map is deprecated - rename call to &quot;#filter_with&quot;&#39;</span> )
  <span class="ruby-identifier">filter_with</span>( <span class="ruby-identifier">map</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-list_finder">
              <b>list_finder</b>( list_parameters )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-list_finder" name="method-i-list_finder" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Deprecated interface replaced by <a
href="ClassMethods.html#method-i-list">list</a> (this is an alias).</p>
<dl class="rdoc-list note-list"><dt>list_parameters
<dd>
<p>Passed to <a href="ClassMethods.html#method-i-list">list</a>.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-list_finder_source')" id="l_method-i-list_finder_source">show</a>
              </p>
              <div id="method-i-list_finder_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 776</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">list_finder</span>( <span class="ruby-identifier">list_parameters</span> )
  <span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span>( <span class="ruby-string">&#39;Hoodoo:ActiveRecord::Finder#list_finder is deprecated - rename call to &quot;#list&quot;&#39;</span> )
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">list</span>( <span class="ruby-identifier">list_parameters</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-list_in">
              <b>list_in</b>( context )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-list_in" name="method-i-list_in" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Implicily secure, translated, dated etc. etc. version of <a
href="ClassMethods.html#method-i-list">list</a>, according to which modules
are mixed into your model class. See <a
href="ClassMethods.html#method-i-scoped_in">scoped_in</a> to see the list
of things that get included in the scope according to the mixins that are
in use.</p>

<p>For example, if you have included <a
href="../Secure.html">Hoodoo::ActiveRecord::Secure</a>, this method
provides you with an implicitly secure query. Read the documentation on <a
href="ClassMethods.html#method-i-acquire_in">acquire_in</a> versus <a
href="ClassMethods.html#method-i-acquire">acquire</a> for information on
the use of secure scopes; as with <a
href="ClassMethods.html#method-i-acquire_in">acquire_in</a> and the
“Secure” mixin, this method becomes for convenience and safety - you
can&#39;t accidentally forget the secure scope:</p>

<pre><code>SomeModel.secure( context ).list( context.request.list )

# ...has the same result as...

SomeModel.list_in( context )
</code></pre>

<p>The same applies to forgetting dated scopes, translated scopes, or anything
else that <a href="ClassMethods.html#method-i-scoped_in">scoped_in</a>
might include for you.</p>
<dl class="rdoc-list note-list"><dt><code>context</code>
<dd>
<p><a href="../../Services/Context.html">Hoodoo::Services::Context</a>
instance describing a call context. This is typically a value passed to one
of the <a
href="../../Services/Implementation.html">Hoodoo::Services::Implementation</a>
instance methods that a resource subclass implements.</p>
</dd></dl>

<p>Returns a secure list scope, for either further modification with query
methods like <code>where</code> or fetching from the database with
<code>all</code>.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-list_in_source')" id="l_method-i-list_in_source">show</a>
              </p>
              <div id="method-i-list_in_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 490</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">list_in</span>( <span class="ruby-identifier">context</span> )
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">scoped_in</span>( <span class="ruby-identifier">context</span> ).<span class="ruby-identifier">list</span>( <span class="ruby-identifier">context</span>.<span class="ruby-identifier">request</span>.<span class="ruby-identifier">list</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-list_search_map">
              <b>list_search_map</b>( map )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-list_search_map" name="method-i-list_search_map" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Deprecated interface replaced by <a
href="ClassMethods.html#method-i-search_with">search_with</a> (this is an
alias).</p>
<dl class="rdoc-list note-list"><dt>map
<dd>
<p>Passed to <a href="ClassMethods.html#method-i-search_with">search_with</a>.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-list_search_map_source')" id="l_method-i-list_search_map_source">show</a>
              </p>
              <div id="method-i-list_search_map_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 785</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">list_search_map</span>( <span class="ruby-identifier">map</span> )
  <span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span>( <span class="ruby-string">&#39;Hoodoo:ActiveRecord::Finder#list_search_map is deprecated - rename call to &quot;#search_with&quot;&#39;</span> )
  <span class="ruby-identifier">search_with</span>( <span class="ruby-identifier">map</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-polymorphic_find">
              <b>polymorphic_find</b>( finder, ident )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-polymorphic_find" name="method-i-polymorphic_find" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Deprecated interface replaced by <a
href="ClassMethods.html#method-i-acquire">acquire</a>. Instead of:</p>

<pre><code>Model.polymorphic_find( foo, ident )
</code></pre>

<p>…use:</p>

<pre><code>foo.acquire( ident )
</code></pre>

<p>This implementation is for legacy support and just calls through to <a
href="ClassMethods.html#method-i-acquire">acquire</a>.</p>
<dl class="rdoc-list note-list"><dt><code>finder</code>
<dd>
<p><a href="ClassMethods.html#method-i-acquire">acquire</a> is called on this.</p>
</dd><dt><code>ident</code>
<dd>
<p>Passed to <a href="ClassMethods.html#method-i-acquire">acquire</a>.</p>
</dd></dl>

<p>Returns a found model instance or <code>nil</code> for no match.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-polymorphic_find_source')" id="l_method-i-polymorphic_find_source">show</a>
              </p>
              <div id="method-i-polymorphic_find_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 758</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">polymorphic_find</span>( <span class="ruby-identifier">finder</span>, <span class="ruby-identifier">ident</span> )
  <span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span>( <span class="ruby-string">&#39;Hoodoo:ActiveRecord::Finder#polymorphic_find is deprecated - use &quot;foo.acquire( ident )&quot; instead of &quot;Model.polymorphic_find( foo, ident )&quot;&#39;</span> )
  <span class="ruby-identifier">finder</span>.<span class="ruby-identifier">acquire</span>( <span class="ruby-identifier">ident</span> ) <span class="ruby-comment"># Ignore &#39;finder&#39;</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-polymorphic_id_fields">
              <b>polymorphic_id_fields</b>( *args )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-polymorphic_id_fields" name="method-i-polymorphic_id_fields" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Deprecated interface replaced by <a
href="ClassMethods.html#method-i-acquire_with">acquire_with</a> (this is an
alias).</p>
<dl class="rdoc-list note-list"><dt>*args
<dd>
<p>Passed to <a
href="ClassMethods.html#method-i-acquire_with">acquire_with</a>.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-polymorphic_id_fields_source')" id="l_method-i-polymorphic_id_fields_source">show</a>
              </p>
              <div id="method-i-polymorphic_id_fields_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 767</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">polymorphic_id_fields</span>( <span class="ruby-operator">*</span><span class="ruby-identifier">args</span> )
  <span class="ruby-identifier">$stderr</span>.<span class="ruby-identifier">puts</span>( <span class="ruby-string">&#39;Hoodoo:ActiveRecord::Finder#polymorphic_id_fields is deprecated - rename call to &quot;#acquire_with&quot;&#39;</span> )
  <span class="ruby-identifier">acquire_with</span>( <span class="ruby-operator">*</span><span class="ruby-identifier">args</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-scoped_in">
              <b>scoped_in</b>( context )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-scoped_in" name="method-i-scoped_in" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Returns an ActiveRecord::Relation instance representing a primitive base
scope that includes various context-related aspects according to the
prevailing mixins included by “this” class, if any - e.g. security, dating
and/or translation.</p>

<p>See Hoodoo::ActiveRecord::Support#full_scope_for to see the list of things
that get included. If there are no “interesting” mixins, the returned scope
will just return the same thing that the <code>all</code> method in <a
href="../../ActiveRecord.html">ActiveRecord</a> would have returned.
Consequently, a default scope <em>will</em> be honoured if one has been
declared, though default scopes are generally considered an anti-pattern to
be avoided.</p>
<dl class="rdoc-list note-list"><dt><code>context</code>
<dd>
<p><a href="../../Services/Context.html">Hoodoo::Services::Context</a>
instance describing a call context. This is typically a value passed to one
of the <a
href="../../Services/Implementation.html">Hoodoo::Services::Implementation</a>
instance methods that a resource subclass implements.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-scoped_in_source')" id="l_method-i-scoped_in_source">show</a>
              </p>
              <div id="method-i-scoped_in_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 109</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">scoped_in</span>( <span class="ruby-identifier">context</span> )
  <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">ActiveRecord</span><span class="ruby-operator">::</span><span class="ruby-constant">Support</span>.<span class="ruby-identifier">full_scope_for</span>( <span class="ruby-keyword">self</span>, <span class="ruby-identifier">context</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-search_with">
              <b>search_with</b>( hash )
            <a href="../../../../classes/Hoodoo/ActiveRecord/Finder/ClassMethods.html#method-i-search_with" name="method-i-search_with" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Specify a search mapping for use by <a
href="ClassMethods.html#method-i-list">list</a> to automatically restrict
list results.</p>

<p>In the simplest case, search query string entries and model field
(attribute) names are assumed to be the same; if you wanted to search for
values of model attributes <code>name</code> and <code>colour</code> using
query string entries of <code>name</code> and <code>colour</code> you would
just do this:</p>

<pre><code>class SomeModel &lt; ActiveRecord::Base
  search_with(
    :name   =&gt; nil,
    :colour =&gt; nil
  )
end
</code></pre>

<p>The <code>nil</code> values mean a default, case sensitive match is
performed with the query string keys and values mapping directly to model
query attribute names and values.</p>

<p>More complex example where <code>colour</code> is matched verbatim, but
<code>name</code> is matched case-insensitive, assuming PostgreSQL&#39;s
ILIKE is there:</p>

<pre><code>class SomeModel &lt; ActiveRecord::Base
  search_with(
    :name =&gt; Proc.new { | attr, value |
      [ &#39;name ILIKE ?&#39;, value ]
    },
    :colour =&gt; nil
  )
end
</code></pre>

<p>Extending the above to use a single Proc that handles case insensitive
matches across all attributes:</p>

<pre><code>class SomeModel &lt; ActiveRecord::Base
  CI_MATCH = Proc.new { | attr, value |
    [ &quot;#{ attr } ILIKE ?&quot;, value ]
  }

  search_with(
    :name   =&gt; CI_MATCH,
    :colour =&gt; CI_MATCH
  )
end
</code></pre>

<p>If you wanted to match against an array of possible matches, something like
this would work:</p>

<pre><code>ARRAY_MATCH = Proc.new { | attr, value |
  [ { attr =&gt; [ value ].flatten } ]
}
</code></pre>

<p>Note the returned <strong>array</strong> (see input parameter details)
inside which the usual hash syntax for AREL <code>.where</code>-style
queries is present.</p>

<p>To help out with common cases other than just specifying <code>nil</code>,
the <a
href="SearchHelper.html">Hoodoo::ActiveRecord::Finder::SearchHelper</a>
class provides a method chaining approach which builds up the Hash used by
<a href="ClassMethods.html#method-i-search_with">search_with</a> and
filter_with. See that class&#39;s API documentation for details.</p>
<dl class="rdoc-list note-list"><dt>*args
<dd>
<p>A Hash. Keys are both search field names and model attribute names, unless
overridden by values; values of <code>nil</code> are used for simple cases
- “where( { attr_name =&gt; value } )” will be the resulting query
modification. Alternatively, pass a callable Proc/Lambda. This is pased the
attribute under consideration (and so you can ignore that and query against
one or more different-named model attributes) and the
context-caller-supplied value to search for. Return <strong>AN</strong>
<strong>ARRAY</strong> of parameters to pass to <code>where</code>. For
parameters to <code>where</code>, see:</p>

<p><a
href="http://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-where">api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-where</a></p>

<p>The Hash keys giving the search attribute names can be specified as Strings
or Symbols.</p>

<p>See <a
href="SearchHelper.html">Hoodoo::ActiveRecord::Finder::SearchHelper</a> for
methods which assist with filling in non-nil values for this Hash.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-search_with_source')" id="l_method-i-search_with_source">show</a>
              </p>
              <div id="method-i-search_with_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/active/active_record/finder.rb, line 716</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">search_with</span>( <span class="ruby-identifier">hash</span> )
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">nz_co_loyalty_hoodoo_search_with</span> = <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">ActiveRecord</span><span class="ruby-operator">::</span><span class="ruby-constant">Support</span>.<span class="ruby-identifier">process_to_map</span>( <span class="ruby-identifier">hash</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
</div>

    </div>
  </body>
</html>
